﻿using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace ParallelRuntimeLibrary.Collections
{
    public interface IConcurrentCollection<T>
    {
        /// <summary>
        /// Adds an object to the <see cref="T:ParallelRuntimeLibrary.Collections.IConcurrentCollection{T}" />.
        /// </summary>
        /// <param name="element">The object to add to the <see cref="T:ParallelRuntimeLibrary.Collections.IConcurrentCollection{T}" />.</param>
        /// <returns>True if an element was successfully added; otherwise, false.</returns>
        /// <remarks>
        /// If the object was successfully added, incrementing the number of elements in the collection by
        /// one, <see cref="M:ParallelRuntimeLibrary.Collections.IConcurrentCollection`1.Add(`0)" /> returns true. If the object was not added, leaving the number of elements
        /// in the collection unmodified, <see cref="M:ParallelRuntimeLibrary.Collections.IConcurrentCollection`1.Add(`0)" /> returns false.
        /// </remarks>
        bool Add(T item);

        /// <summary>
        /// Removes and returns an object from the <see cref="T:ParallelRuntimeLibrary.Collections.IConcurrentCollection{T}" />. The return value indicates whether an
        /// object was successfully removed.
        /// </summary>
        /// <param name="result">
        /// When this method returns, if the removal succeeded, contains the removed object. If no object was
        /// available to be removed, the value is unspecified. This parameter is passed uninitialized.
        /// </param>
        /// <returns>True if an element was removed and returned; otherwise, false.</returns>
        /// <remarks>
        /// If an object was successfully removed, decrementing the number of elements in the collection by
        /// one, <see cref="M:ParallelRuntimeLibrary.Collections.IConcurrentCollection`1.Remove(`0@)" /> returns true. If an object was not removed, leaving the number of elements
        /// in the collection unmodified, <see cref="M:ParallelRuntimeLibrary.Collections.IConcurrentCollection`1.Remove(`0@)" /> returns false.
        /// </remarks>
        bool Remove(out T item);

        /// <summary>Copies the items from the <see cref="T:ParallelRuntimeLibrary.Collections.IConcurrentCollection{T}" /> instance into a new array.</summary>
        /// <returns>An array containing copies of the elements of the collection.</returns>
        /// <remarks>
        /// The returned elements should mirror what a call to GetEnumerator would return at an instant in
        /// time. If the collection is empty, an empty array will be returned.
        /// </remarks>
        T[] ToArray();

        int Count { get; }
    }
}
